═══ 1. Introduction ═══

                                   PMsndX 1.0
                                       by
                                William S. Hiles
                             copyright WiSHware Inc.

First off, what is PMsndX?  PMsndX is the acronym that I created to mean 
Presentation Manager sound eXchange. PMsndX was written specifically for OS/2 
to provide an editor for sound samples of many different formats.  The editor 
goes beyond just a cut and paste tool like the Digital Audio applet provided 
with OS/2 by providing a rich set of tools for manipulating samples in memory. 
PMsndX utilizes a large set of features of OS/2 and if present, the MMPM/2 
interface is used to allow playback of any of the supported formats from 
memory. 

Using dialog boxes, PMsndX provides an intuitive user interface for utilizing 
the clipboard, MMPM/2 playback, and algorithms for adding special effects to 
samples.  Everything is integrated together to make it easy to manage the 
process of extracting or building samples in many different formats. 

Wow, you are still reading!  Well, now for some information on the user 
interface.  There is nothing more frustrating than trying to use a program with 
a difficult or complex user interface.  Twelve years ago I started programming 
a TI99/4A in assembly language and from the start I have put more effort into a 
clean user interface than anything.  It wasn't till I ran across JOEVIEW that I 
realized that OS/2 had one of the most capable environments that I had seen. 
Presentation Manager programming has got to be one of the easiest environments 
to use and is a breeze compared to Microsoft Windows or the X environment. 

In any case, I spent more time on the user interface of this program than I 
ever thought possible.  It is designed around a single coordinating window 
populated by bitmaps.  Each bitmap has some sort of image that changes when the 
button is pushed.  To make sure that the literate people out there (or the icon 
impaired) understand the buttons, I put a bit of text on them to describe the 
function. 

Now, I have used programs on a lot of platforms and I have my favorites along 
with those that annoy me too.  My pet peeves are the applications like Procomm 
for Windows which just assumes that you want the darn thing to fill up your 
screen.  Or something like Microsoft Word which has so many menus and submenus 
that it is hard to remember where a function is.  So, taking this into account, 
I designed the interface such that the main functions of the program are 
accessible from the main panel.  Pressing the button for the function will then 
bring up a dialog box which asks the user for the necessary information. 
Pushing the button again will remove the dialog box.  I prefer this interface 
because it provides a single point of control.  Well, you just need to play 
with it for a bit to get an understanding of what I am talking about here. 


═══ 2. Conventions ═══

Throughout the documentation provided with PMsndX a number of terms are used 
which may be common to Presentation Manager programs but uncommon to 
conversational English.  There are also terms which are specific to PMsndX 
which may be new to a user of this program.  The intent of this section is not 
to recreate the OS/2 documentation; rather, it is intended to identify some 
basic terms necessary to understand the language used in this documentation. 

Presentation Manager: 
   The Presentation Manager is the Graphical User Interface (GUI) for most OS/2 
   systems.  There are other GUIs available for OS/2 but this is the most 
   common and the one that comes with OS/2 out of the box.  In general most 
   people refer to the Presentation Manager by the acronym PM. 

SYSTEM MENU: 
   Every PM program for OS/2 generally provides a SYSTEM MENU through an icon 
   in the upper left corner of the window interface to the user.  By default, 
   the system menu will contain the basic functions necessary to control the 
   window for on the OS/2 PM desktop. 

TITLE BAR: 
   In order for a window to be moved about the desktop with the mouse, a window 
   must have a titlebar.  This is the thick bar at the top of the window.  The 
   titlebar provides another function in that it allows the program to display 
   relevant messages to the user. 

MINIMIZE BUTTON: 
   A PM program may provide various control buttons for a window in the top 
   right corner of a window.  One of these buttons is the MINIMIZE button. When 
   the user selects this button, the window will be removed from the desktop 
   and replaced by a small icon somewhere on the screen.  In most cases, the 
   icon is placed at the bottom of the screen.  To restore the window the user 
   can double click on the icon or can use a mouse button to bring up a menu 
   and select Restore. 

MAIN CONTROL PANEL: 
   The main control panel for PMsndX is the window that is initially displayed 
   when the program is executed.  This window is the main point of control for 
   the program and provides access to all of the above mentioned controls as 
   well as access to all of the functions of the program. 

ACCELERATOR KEYS: 
   The buttons on the main control panel and many of the controls in the 
   associated tools provide accelerator keys.  These are marked on the displays 
   by an underline.  To access the particular item without using the mouse, 
   hold down the ALT key and press the underlined key.  As an example, to 
   activate the OPEN button on the main control panel, hold down the ALT key 
   and press the letter o. 


═══ 3. Mouse Pointer ═══

The mouse pointer is used as an indication of the state of the program.  When 
the program is processing, the mouse pointer will be changed to a small dial 
with 10 markers on the dial.  The percentage of work completed is then 
indicated by the hand of the dial.  When the dial reaches the vertical 
position, the work has been completed. 

There is one exception to this operation.  When the echo effect is used, the 
dial for the pointer will rotate more than once. This is because the results of 
the echo effect change the length of the data depending on the markers and 
volumes such that the resulting length is unpredictable. 

PMsndX uses multiple threads to accomplish many of its tasks.  As a result, 
when a file is loaded the clock may turn more than once because each thread 
will run as the resources that it is waiting on complete.  An example of this 
is opening a file when the playback box is open.  In this case, as soon as the 
file is completely loaded, the playback task will immediately start copying it 
to the buffer for the playlist and the clock will turn around a second time. 


═══ 4. System Menu ═══

As with any OS/2 program written for the Presentation Manager, PMsndX has an 
icon in the top left corner of the control window.  Pressing this icon will 
bring up a menu of system operations. 

The menu items provided in the system menu are: 

Restore        Restore the windows after being minimized 
Move           Move the control window 
Minimize       Minimize all of the windows of PMsndX to an icon 
Close          Close the all windows and exit 
About          Display information about the author and version and 
               registration 
Welcome        Display information about what is new to this version 
Help           Bring up the help system 
Reset Size     Reset the size of the main control panel to the default 


═══ 4.1. Restore ═══

During the use of PMsndX, the user may select to Minimize the windows to an 
icon on the desktop.  To restore the window from the icon the user may either 
double click on the icon or may press a mouse button while the pointer is over 
the icon to bring up the system menu and select the restore item. 


═══ 4.2. Move ═══

PMsndX provides the standard controls for moving the windows around on the 
desktop.  It is generally easiest to use the mouse to select the titlebar of 
the window and drag the window to the new location.  If the user uses the 
system menu to move the window, the mouse will be centered in the control 
window and any movement of the mouse will move the window until a mouse button 
is pressed. 


═══ 4.3. Minimize ═══

All of the windows of PMsndX can be minimized quickly by either selecting the 
minimize button on the upper right corner of the control panel or by using the 
Minimize menu item of the system menu.  Either action performs the same 
function. 


═══ 4.4. Close ═══

To exit PMsndX the user can select the Close menu item from the system menu. 
This is the default selection of the menu which enables the user to double 
click on the PMsndX icon in the top left corner of the control panel to exit 
the program.  The user may also use the Exit button on the control panel to 
perform the same function. 


═══ 4.5. About ═══

To find out the current version and other information about PMsndX the About 
menu item can be selected from the system menu.  This display also shows the 
current registration status of the program and the registration can be updated 
by pressing the REGISTER button. 

PMsndX is just one of the programs written by the Author for Intel based 
machines.  All programs developed under the WiSHware Inc. name have been 
developed solely by the author (duhh, the Author is the sole member of the 
company) and are copyrighted by US Copyright laws. 


═══ 4.6. Welcome ═══

The HISTORY.TXT file contains a very complete list of all the changes between 
each of the versions.  When viewed as a whole, it also summarizes the total 
functionality of PMsndX.  Each version has specific changes which are 
highlighted in the Welcome display. This display also shows the current 
registration status of the program and the registration can be updated by 
pressing the REGISTER button. 


═══ 4.7. Help ═══

Selecting this option from the system menu performs the same function as 
pressing the Help button on the main control panel.  This brings up the online 
help system for PMsndX. 


═══ 4.8. Reset Size ═══

The default button size for the display is 64x64. At any time, the user may 
select to reset the size of the main control panel so that it returns to the 
defaults.  The main control panel may be resized, using the border of the 
window. 


═══ 5. Resizing the main panel ═══

In accordance with the recommended Common User Access (CUA) guidelines, the 
main control panel may be resized using the border of the window.  The 
horizontal and vertical proportions of the buttons is always fixed such that 
the overall window proportions will display the buttons properly. When the 
width of the main panel is changed, the height is automatically adjusted to 
maintain the proper shape of the buttons. 

Note:  Note.  To resize the window, either the corners or the vertical sides of 
       the window must be used.  The horizontal sides of the window have no 
       effect when used alone. 


═══ 6. Buttons ═══

The main control panel provides the user with access to all tools and functions 
trough a set of buttons.  Each button contains an icon and a single word which 
describes the function of the button. The buttons have been designed as toggle 
type push buttons.  To select a particular button, the mouse must be positioned 
over the button and the first mouse button pressed.  This will depress the 
button and activate a dialog for the desired function.  The dialogs present 
information to the user about the desired operation and request input from the 
user to complete the operation. 

The control panel is the main point of control for both activating and 
deactivating a particular function.  The dialog boxes can be removed from the 
screen by positioning the mouse over a depressed button and pressing the first 
mouse button.  The dialog box will be removed and the button will return to the 
non-depressed position. It is important to note that when a dialog box is 
removed through this means, any information in the dialog is ignored and the 
function is canceled.  For each dialog box, the user must enter all of the 
information required and then select the appropriate action on the push buttons 
at the bottom of the dialog box. The Open and Save Dialog boxes may also be 
removed once the file operation has been completed.  This is the default 
operation but may be changed so that the dialogs are not automatically 
dismissed by deselecting the "AUTO Dismiss" box in the lower right corner of 
the dialog window. 

Now for the buttons.  There are six buttons on the main control panel.  These 
are listed below with a brief explanation of their function. 

               Opens and reads a new sample file 
               Saves the current sample to a file 
               Plays the current sample to an audio device 
               Edit using the Clipboard 
               Displays options to save between sessions 
               Displays a notebook of tools 
               Displays general help about PMsndX 
               Exit PMsndX 


═══ 6.1. Open ═══

The dialog box for opening a file and reading the sample into memory is 
accessed from the OPEN button on the main control panel.  When reading in a 
file, PMsndX will attempt to open the file as the type indicated by the 
extension on the filename.  However, in the event that the file cannot be 
loaded by the extension, PMsndX will automatically try to determine the type of 
the file as it reads it.  If the sample header does not match any of the known 
header types, PMsndX will refuse to load the file. 

When loading a file, the user may select to force PMsndX to load a file in a 
specific format.  This is required to load headerless formats (i.e. the formats 
marked as RAW).  To override the file format, select one of the buttons in the 
Format box. 

Note:  If a Format override is specified, the file must still match the given 
       format if it contains a header.  PMsndX will automatically recognize the 
       header format and load it using the correct format. 

Once a file has been selected, either double click on the file name or press 
the Load button.  During the time that the file is being loaded, the user may 
press the Abort button to stop the loading process.  All data which may have 
previously been loaded will be discarded. 

The File Type pulldown box works in combination with the File EA pulldown box. 
To select all files of a particular type based on the name of the file (e.g. 
*.wav, *.au, *.iff, etc.) first select the name extension from the File Type 
pulldown list, and then select <All Files> from the File EA pulldown list. 

By default, the OPEN dialog box is automatically dismissed when the file has 
been loaded.  If an error occurs during the loading process, the dialog will 
not automatically dismiss itself.  To disable this feature (i.e. force the 
dialog box to remain visible even after a file has been loaded) deselect the 
AUTO Dismiss checkbox in the lower right corner of the window. 


═══ 6.2. Save ═══

The dialog box for saving a file to disk is accessed from the SAVE button on 
the main control panel.  When saving a file, the extension of the file will 
automatically determine the type of output to write for the file (e.g. if the 
extension entered by the user is .wav, then the file will be saved in WAVE 
format.) or the user may override the file type by selecting one of the buttons 
for the type of file. 

When saving a file, the extension of the file normally determines the format to 
save the file in.  The primary use of this feature will be to promote the use 
of standard file name extensions for the various sample types. However, the 
user may specify that the information is stored in a particular format 
regardless of the file extension.  In the event that no extension is specified 
for the file, the PMsndX will automatically save the file under the specified 
name under the format currently selected in the FORMAT field.  The available 
formats for file operations are listed below. If the file type of Undefined is 
selected, then the extension of the file will be used to determine the file 
type. 

APPLE (.aif)   Apple 8/16 bit unsigned multi-channel samples 
SUN (.au)      Sun/DEC/NeXT 8 or 16 bit single channel signed data samples or 8 
               bit ULaw samples. 
MAC (.hcm)     Apple Macintosh 8 bit single channel samples 
RAW (.ub)      Raw 8 bit single channel unsigned samples without header 
               information. 
RAW (.sb)      Raw 8 bit single channel signed samples without header 
               information. 
RAW (.uw)      Raw 16 bit single channel unsigned samples without header 
               information. 
RAW (.sw)      Raw 16 bit single channel signed samples without header 
               information. 
RAW (.ul)      Raw 16 bit U-Law single channel samples 
IRACAM (.sf)   Software produced 16 bit signed samples. 
PC (.voc)      Creative Voice file format, 8 bit single channel unsigned 
               samples 
SAMP (.smp)    Turtle beach samplevision files. 
PC (.wav)      Windows or OS/2 8 bit unsigned/16 bit signed multi-channel data 
               samples 

The Save Directory checkbox allows the user to save the current save path 
between sessions without having to open the Settings dialog box.  when this box 
is selected, if the OK button is selected, the specified directory path will be 
saved when the program has is terminated. If the SAVE DIRECTORY is deselected 
before the program is terminated, the path will not be saved.  All file paths 
are remembered during each session and the SAVE DIRECTORY box allows the user 
to store this path between sessions. 

Note:  The file path is not saved until the program has been terminated. 

By default, the SAVE dialog box is automatically dismissed when the file has 
been loaded.  If an error occurs during the loading process, the dialog will 
not automatically dismiss itself.  To disable this feature (i.e. force the 
dialog box to remain visible even after a file has been loaded) deselect the 
AUTO Dismiss checkbox in the lower right corner of the window. 


═══ 6.3. Playback ═══

So, you are interested in playing some samples from my little program?  Good. 

The ability to play a sample is not intended to provide the full capabilities 
of the digital audio player.  It is intended to allow samples to be played 
without having to save them to disk.  Additionally, this feature allows the 
user to play a file of any format currently supported by PMsndX.  The sample 
rates are limited to those supported by the audio device and if a sample is 
loaded with an odd sample rate which is not supported, it must be converted to 
a useable sample rate before it can be played. 

Note:  Whenever a sample is loaded and the PLAYBACK dialog is open, PMsndX will 
       attempt to load the audio buffers with the sound data.  If the sample 
       cannot be played (the number of channels or the sampling rate is not 
       supported by the audio adapter) a warning is displayed.  PMsndX will not 
       attempt to play a file that the audio adapter does not support. 

If you don't have MMPM/2 installed with your OS/2, don't worry.  PMsndX has 
been written to provide as much of its capabilities as it can with or without 
MMPM/2 installed. None of the tools, nor the editor require MMPM/2 to perform. 
However, the playback button will be marked out if MMPM/2 is not installed 
because there will be no means to play the sounds. 

When the playback button is pressed, a dialog box is opened which contains a 
set of standard controls for playing sounds.  A checkbox is provided to allow 
the samples to automatically repeat when the end of the playback is reached. 

The controls for the playback player are basically the same as those used on 
the digital audio player provided with the MMPM/2 package for OS/2. 

          Starts or continues playback. 
          Starts recording. 
          Stops playback. 
          Pauses playback. 

Note:  Recording has not been implemented at this time.

The Playback dialog provides a checkbox to allow a sample to be looped such 
that it will continuously repeat.  When this checkbox is selected, the repeat 
function is enabled. Playback can be stopped by deselecting the repeat checkbox 
(in which case, the sample will complete playback befor stopping) or by 
pressing the button. 

The Playback dialog also has the capability of playing a selected range and/or 
a selected channel.  If the edit dialog is active, the range and channels for 
manipulation may be used to select the part of a sample to be played. When the 
Use Channel Selection box is selected, the selected channel will be played. 
This allows the user to extract and play individual channels.  Similarly, when 
the Use Range Selection box is selected, the specified range in the editor will 
be played. 

Note:  If the edit dialog window is not open, the full sample (including all 
       channels) is automatically used. 


═══ 6.4. Edit ═══

The editor is designed to be compatible with the format of data pasted to the 
clipboard using the OS/2 Digital Audio Application to allow bi-directional use 
of the clipboard between the two applications.  To describe the use of the 
editor each of the categories of controls will be described.  Most are very 
obvious, but some (particularly the operation buttons) have rules of 
operation). 

The editor is the central point of control for selecting the range and channels 
for all operations.  As a result, when an operation is being performed (as 
indicated by the mouse pointer displayed as a clock face) if the range is 
changed or the channel to manipulate is changed, a warning beep will be 
produced; however, the display will indicate that the selection has been made. 
For the editor, the change will be made, but the rest of the tools and playback 
will not be updated until another selection is made causing changes to the 
channels or range.  Additionally, attempts to perform operations (i.e. Cut, 
Paste, Copy, Remove, and Zero) will result in a audible warning and the 
function will not be performed. 

As with the other tools, operations which take a significant amount of time to 
accomplish will provide an indicator for the percentage of the task completed. 
Operations which copy data to the clipboard or delete data from memory utilize 
the DMA memory transfers and are fast enough that the indicator is not used. 
Operations which copy data from the clipboard use the indicator because the 
operation is much more complicated. 

Note:  The editor has been written without the use of the MMPM/2 libraries. 
       Although MMPM/2 has all the functions necessary to perform the clipboard 
       operations, they can only be used if MMPM/2 is installed.  Since this 
       program has been written to do its core work on any OS/2 system (with or 
       without MMPM/2), everything is done manually.  This provided a bit more 
       control over the PASTE operation and it is still very quick. 

The editor has been written to provide a robust method of manipulating parts 
(or all) of a sample.  The functions are broken down into groups (marked by a 
box around the group). 

Channel Displayed: 

The edit dialog box allows the user to view a single channel at a time through 
the graphical display.  The channel to be displayed is selected using radio 
buttons which are enabled based on the number of channels in the current sample 
in memory. 

Area: 

When using the Copy, Cut, Zero, and Remove operations, the user selects the 
area of the sample to be affected by either selecting the entire sample or 
selecting a part of the sample.  When the radio button for the "Entire Sample" 
is selected, the start and end will be set to the beginning and end of the 
sample respectively.  To select a part, the user may either select the Select 
Part radio button or use the left or right buttons to select the start and end 
respectively for the interval of the operation. 

Selection: 

The user may specify a specific time for the begin or end of the interval for 
the desired operation by typing the time directly.  The editor will 
automatically adjust the time down to the nearest actual sample.  To activate 
the Selection entry fields, select the Select Part radio button in the Area 
field. 

Manipulate: 

This is probably the one field to draw the most confusion.  This group of 
buttons allows the user to specify which channel to operate on.  By default the 
editor will operate on all channels of a sample.  However, the user may select 
a specific channel for the operation by pressing the "Selected Chan" radio 
button and then selecting the channel for the operation.  Once the operation is 
performed, the Manipulate group will default back to All Channels. 

 The editor is integrated into the PMsndX such that the Tools and the Playback 
dialogs utilize the information from the editor.  Each tool indicates that it 
uses the range or channels selected in the editor through a checkbox in the 
lower left corner of the tool.  The Playback dialog provides checkboxes to 
enable or disable the usage of the channel and range selection. 

Each of the groups provides the user with a means to select the parameters of 
the various operations.  Each operation has a set of rules defining how they 
behave under the various conditions.  These are defined in the following text. 

Rules for cut: 

1.  If the channel to operate on is "ALL", the copy all of the data over the 
specified interval and shift all data over to the left. 

2.  If the channel to operate on is specified, then copy the data over the 
specified interval for that single channel to the clipboard, and shift the data 
after the interval over to the left while clearing the end of the data for the 
specified channel. 

Rules for paste: 

The PASTE button is used the paste the contents of the clipboard into memory. 
If the SHIFT key is pressed the text on the PASTE button will change to MERGE. 
When the MERGE button is pushed, the editor will merge the data from the 
clipboard with the data in memory.  When the merge function is used the rules 
for PASTE apply except that the data is averaged equally instead of being 
inserted. 

The paste operation varies depending on the number of channels in the current 
sample and the number of samples in the data on the clipboard. After the paste 
operation, the start marker will be set at the beginning of the sample pasted 
from the clipboard and the end marker will be set to the end of the new data. 

1.  If there is no current data, then just copy the clipboard directly to 
memory. 

2.  If the number of pasted channels is the same as the current data, then past 
the data in based on the selected channel for manipulation. 

Note:  When merging, the data is averaged based on the selected channel for 
       manipulation.  Any excess difference between the length of the two will 
       be left unafffected.

3.  If the number of pasted channels is 1, then just copy the data to the 
channel(s) selected for manipulation and insert blank space for the 
corresponding channels which are not being manipulated.  If the number of 
channels for manipulation is "ALL" then duplicate the data for the single 
channel across all channels of the current data. 

Note:  If the number of merged channels is 1, then average the data from the 
       clipboard to the channel(s) selected for manipulation.  If the length of 
       the samples does not match the data will be averaged for the common 
       length of the two and excess will not be modified.

4.  If the number of pasted/merged channels is less than the current number of 
channels (but greater than 1), then 

a) if the channels selected for manipulation is set to "ALL" then copy the 
channels from the clipboard directly into the current sample and zero out the 
non-existent channels. 

Note:  When merging, average the data from the clipboard directly into the 
       current sample and leave the non-existent channels unaffected.

b) copy the first channel from the pasted sample into the selected channel for 
manipulation. 

Note:  When merging, average the first channel from the clipboard with the 
       selected channel for manipulation.

5.  If the pasted/merged sample has more channels than the current sample, then 

a) if the channels selected for manipulation is set to "ALL" then create the 
new channels in the existing data and set all non-existent channels in the 
existing data to zero. 

Note:  When merging, average the existing channels and copy the clipboard data 
       directly to the channels that did not exist in memory. 

b) copy the first channel from the pasted sample into the selected channel for 
manipulation. 

Note:  When merging, the first channel is merged into the selected channel for manipulation.

6.  If all of this fails, then just warn the user and give up. 

Rules for Copy Operation: 

1.  If the channel to operate on is ALL, copy all of the data over the 
specified interval to the to the clipboard. 

2.  If the channel to operate on is specified, then copy that single channel to 
the clipboard. 

Rules for Zero operation: 

Set the data over the specified interval to 0 for the channels specified. 

Rules for Remove operation: 

1.  If the channel to operate on is "ALL", then remove the data over the 
interval specified and shift all data to the left. 

2.  if the channel to operate on is specified, then remove the data for that 
channel over the interval and shift the end of that channel to the left while 
zeroing out the end of the channel. 

Rules for Clear operation: 

This operation clears all data from the clipboard.  It has no effect on data 
currently in memory. 

UNDO: 

PMsndX utilizes a lot of memory to ensure that the current data in memory is 
not lost if an operation fails.  Normally the original data is deleted from 
memory once an operation is completed to reduce the long term memory 
requirements of the program.  However, If the Enable UNDO checkbox is selected 
from the settings display, PMsndX will store a single buffer for performing one 
level of UNDO. 

After any operation from the toolbox, any of the manipulations from the editor, 
or after loading a new file, if the UNDO option is enabled, the current data 
will be stored in a buffer.  Pressing the UNDO button from the editor will swap 
the current memory with the buffer.  Pressing UNDO again will swap them back. 
With this setup, the UNDO functions as a redo button. 

Note:  The UNDO capability is only available in the registered version of 
       PMsndX. 


═══ 6.5. Settings ═══

PMsndX can store a number of settings that users commonly set in a file called 
pmsndx.ini.  This file is always located wherever the executable program is 
found. 

From the SETTINGS dialog box the user may select to save the current window 
positions, open file path, save file path, maximum memory and enable MMPM/2 
Support requirements of the program. 

The window positions and file paths are maintained as long as PMsndX is 
running.  When PMsndX is terminated, it will not save the current positions and 
paths for file operations unless the boxes are checked in the SETTINGS dialog 
box.  Selecting these buttons has no effect on remembering the current window 
positions during a single session; rather, they only affect saving the 
information between sessions. 

Note:  The information in the SETTINGS dialog box is only saved when the 
       program is terminated.  If the SAVE CURRENT items are deselected, then 
       the information will not be saved between sessions. 

Window Positions During a session, the user can move any of the dialog boxes 
around on the screen.  If the WINDOW POSITIONS box is checked, these window 
positions will be saved when the program is terminated.  If this button is 
deselected before the program is terminated, the next session will revert to 
the previous window positions saved by the program.  By default, if no window 
position has been saved for a particular window, the window will be opened in 
the lower left corner of the desktop. 

File Open Path The file path for loading samples into memory may be saved 
between sessions by selecting the FILE OPEN PATH button.  If this button is 
selected, the last file open path will be saved when PMsndX is terminated.  If 
this button is deselected before the program is terminated, the next session 
will revert to the path from the previous session. If no information is saved 
for the program at any time, the current path will become the default path for 
open operations. 

Note:  This box may be selected from either the SETTINGS dialog box or from the 
       OPEN DIRECTORY button on the OPEN dialog box. 

File Save Path The file path for saving samples to a file may be saved between 
sessions by selecting the FILE SAVE PATH button.  If this button is selected, 
the last file save path will be saved when PMsndX is terminated.  If this 
button is deselected before the program is terminated, the next session will 
revert to the path from the previous session. If no information has not been 
saved between sessions, the current path will become the default path for save 
operations. 

Note:  This box may be selected from either the SETTINGS dialog box or from the 
       SAVE DIRECTORY button on the OPEN dialog box. 

Maximum Sample Memory PMsndX takes advantage of OS/2's advanced memory 
management facilities.  When the program is started, it only takes up the 
memory required for the executable to load.  PMsndX then reserves the amount of 
memory specified by the SETTINGS box from OS/2 but does not commit this memory. 
This means that the program has requested that OS/2 allocate the necessary 
resources to manage the amount of memory specified.  Until the memory is 
actually committed it is not taken from the system's memory pool.  When a sound 
sample is loaded into memory, PMsndX then requests that OS/2 commit the 
necessary memory before it loads the sample.  When a new sample is loaded, the 
previous memory is decommitted and the procedure is repeated. 

Although this minimizes the actual amount of physical memory required by 
PMsndX, it still provides the potential to cause OS/2 to have to commit more 
memory than is available on the system.  To avoid this problem, PMsndX provides 
the user with the ability to limit the amount of memory which can be committed 
by OS/2.  The user may either specify that the program automatically determine 
the maximum or that it set the maximum at a specific value. 

Memory is primarily used to hold samples for operations; however, whenever the 
sound is manipulated in such a way that either the output has a different 
number of samples or the operation requires the samples to remain in tact 
during the entire operation, additional memory is used to hold the new data. 
Once the operation has been completed, the memory is freed.  When setting the 
maximum memory, the user must take into account the size of the data in memory 
as well as the size of the results of any operations. With the exception of 
Sampling Rate changes, the maximum memory requirements will not exceed twice 
the size of a sample.  When changing rate, the size is dependent on the new 
sampling rate.  If the new rate is higher than the current rate, the memory 
requirements will increase.  If the new rate is lower than the original rate, 
the memory requirements will shrink. 

If the user selects the AUTO mode for memory (the default), PMsndX will limit 
the memory usage to 32 megabytes.  This is generally more memory than most 
systems have but allows for a very large sample file to be loaded. 

If the user chooses to limit the memory to a specific value, the AUTO checkbox 
can be turned off and a value may be entered.  Since the minimum OS/2 memory 
block size is 4096 (4k) bytes, the user may specify the number of 4k pages for 
the limit.  The user may either use the up and down arrows to increment or 
decrement the amount of memory or may place the cursor in the window and type 
the specific value. 

Enable MMPM/2 Support 

PMsndX supports playing samples from memory directly to the MMPM/2 digital 
audio device of OS/2.  This allows samples to be played without having to save 
the sample to disk in the native .WAV format.  The settings dialog box provides 
controls for disabling or enabling MMPM/2 support and for controlling the 
actions taken when a file is loaded (e.g. Play sample on load, convert to a 
standard rate when loaded, and exit after play from the command line). 
Additionally, the digital audio device may be specified. 

If the MMPM/2 capabilities of the program are not needed or if MMPM/2 support 
is not installed on a particular system, the MMPM/2 may be disabled from the 
settings dialog box.  By disabling the MMPM/2 support, the button on the main 
control panel for playback is disabled.  By default the program will enable 
MMPM/2 support.  If MMPM/2 is available but disabled and the playback button is 
selected, a message is displayed to the user to indicate that the setting 
should be turned on from the settings box. 

The controls for MMPM/2 and the ability to play the "playlist" using MMPM/2 
utilize the files SW.DLL and MDM.DLL.  These are part of the standard MMPM/2 
distribution and must be present in the DLL path for the MMPM/2 portion of this 
program to operate.  The MMPM/2 support is not linked into the executable of 
this program.  Rather, it is only loaded when the user enables it.  This allows 
the program to run on machines which do not have MMPM/2 installed. 

The MMPM/2 functionality of PMsndX has been implemented to share the audio 
device with other programs on the system. However, if by disabling the MMPM/2 
support, the audio device is freed up completely. 

Play on Load 

If the Play on Load box is selected, a sample is immediately played when it is 
loaded into memory.  To provide control during playback, the playback dialog 
box is opened after the file has been loaded.  When this feature is used in 
conjunction with the exit after play feature, PMsndX provides the ability to 
play any supported sample file format from the command line and have the 
program exit when it is finished. 

If this parameter is not specified, the sample will still be loaded from the 
command line; however, it will not be played until the user accesses the 
playback dialog. 

Note:  When a filename is specified on the command line, the control panel and 
       the dialog boxes are not opened.  The intention of this operation is to 
       allow the program to play without being intrusive. 

Exit after Play 

The Exit after Play option provides the ability for PMsndX to exit after 
playing the sample when the file is loaded from the command line.  This is 
primarily intended to provide a means to play any of the supported formats from 
the command line. 

Device 

Obviously not every machine has the same digital audio device.  PMsndX provides 
a means to use a different audio device than the default digital audio 
interface.  By default the device name is Waveaudio01.  Any Waveaudio device 
may be selected by entering the device name in the Device entry field. 

After the user has set all of the information in the SETTINGS dialog box, the 
DO IT button must be used to save the changes. When this button is pressed, the 
dialog box is dismissed and the settings are applied. 

Note:  If a sample is currently loaded into memory and the Maximum Sample 
       Memory is changed, the sample data will be flushed from memory.  A 
       warning box will be displayed to indicate the result of this operation. 

To dismiss the SETTINGS box without saving any changes, the CANCEL button can 
be used.  This has the same effect as pushing the SETTINGS button on the main 
control panel when the SETTINGS box is displayed.  All information entered by 
the user is cleared and the SETTINGS remain unchanged. 


═══ 6.6. Tools ═══

Using a notebook to display the TOOLS has some unique presentation advantages. 
Primarily the notebook allows the effects to be displayed in a single dialog 
window.  Since each effect is mutually exclusive of any other tool this 
approach displays the maximum information that the user can utilize at any 
time.  Another approach would have been to develop a dialog box for each tool. 
This approach has the disadvantage that it would require a second control panel 
to select the specific tools.  This would violate the approach of providing a 
single control panel for the user and would necessitate managing a number of 
different windows which could potentially clutter the screen.  The notebook is 
a clean and aesthetically pleasing means for managing the tools. 

The heart of manipulating the samples is accessed from the TOOLS notebook. 
Some of the pages of the notebook provide information while others let the user 
apply a particular effect on the current sound sample.  The TOOLS notebook can 
be dismissed by pressing the TOOLS button on the main control panel or by 
pressing the DISMISS button at the bottom of the Tools notebook. The tabs on 
the notebook provide access to the Info, Type, Average, Duplicate, Band Pass, 
Low Pass, Rate, Speed, Echo, Invert, Reverse, Vibro, Volume, Fade, and Balance 
functions for manipulating the samples. 

The notebook may be navigated by either selecting the tab on the right of the 
book for the desired function or by using the small Plus and Minus buttons at 
the bottom of the notebook.  Using the Plus and Minus buttons will move through 
the notebook a single page at a time.  The information for each function are 
divided into the following categories. 

To select the tabs using the keyboard, the focus for the notebook must be set 
for the notebook container (by clicking the mouse outside of one of the tools 
or by pressing the ALT key and the UP arrow). Selecting any character that is 
underlined will bring that page to the top of the display. 

The notebook can be displayed regardless of the presence of sample data in 
memory.  When no sample is present, the pages of the notebook will be 
invalidated but can still be viewed. 


═══ 6.6.1. Info ═══

The Info page displays all of the relevant information about the samples 
currently in memory.  This includes the following categories: 

Load Format     One of the formats which the program can save or open 
Data Type       The default extension for this file format. 
Data Style      SIGNED, UNSIGNED, ULAW, or ALAW 
Channels        Number of channels in the sample 
Sampling Rate   The number of samples taken each second 
Data Size       BYTE (8 bits), WORD (16 bits), LONG (32 bits) 
Samples         The number of samples that make the file 
Comments        Some sample files may contain comments.  Any comments found are 
                displayed in this window 
Byte Order      The natural order of the bytes in each sample.  This field can 
                display either Big Endian or Little Endian 


═══ 6.6.2. Type ═══

The type of the file is determined by the header written to the beginning of 
the file.  See Save for information how the file type is determined when a file 
is saved to disk.  Additionally, the user may use the this tool to change the 
Load Format (displayed in the Info page of the tools notebook).  When the file 
is saved, the default file format will automatically be set to whatever has 
been chosen on this page of the notebook.  Changing the file name extension or 
selecting a file format in the SAVE dialog will override this setting. 

Each file format utilizes different headers for the actual data.  By selecting 
one of the standard formats on this page the Info page will show the user how 
the samples will be saved.  The fields that are most likely to change are the 
Load Format, Data Type, Data Style, and Data Size. 


═══ 6.6.3. Average ═══

A sample with an even number of channels may be averaged to produce a sample 
with half the initial number of channels. For example, a sample with four 
channels can be averaged to produce a sample with two channels and a sample 
with two samples can be averaged to produce a sample with one channel. 

Channels may be averaged in three ways.  The simplest is to take the left or 
right channel data as the final data.  A more complex method is to average the 
samples of the left and right to produce a center sample. The results of these 
operations are significantly different and can result in very different output 
samples. 

When a sample contains four channels, it is composed of four sound sources at 
45 degrees in each quadrant.  This corresponds to the Front Left, Front Right, 
Rear Left, or Rear Right.  To average these into two channels the user can 
select to use any of the four channels or to average based on the left or 
right. To select or average any combination of the channels into either of the 
output channels, check the box for the channels from the source sample.  To aid 
in this, two radio buttons have been provided which enable or disable the 
selection of check boxes in the second channel depending on the number of 
output channels selected. 


═══ 6.6.4. Dupe ═══

Channels can be duplicated such that a single channel sample can be made to 
have two channels which are identical or two channels can be duplicated to form 
four channels. 

When copying two channels to 4, PMsndX allows the user to specify which of the 
input channels will be placed on the output channels.  In this way, a single 
channel of a dual channel sample can be copied to any of the four output 
channels. 


═══ 6.6.5. Band Pass ═══

This tool provides the ability to apply a band-pass filter to a sample. The 
frequency response for the filter is designed to drop logarithmically around a 
center frequency.  The slope of the drop at the desired start (Wp) and end (Ws) 
of the filter varies with the distance between the Wp and Ws.  This width is 
used to determine the slope of the dropoff at the edges of the filter.  The 
frequencies at Wp and Ws will be approximately half of their original 
amplitudes and all frequencies outside of the Center - Wp and the Center + Ws 
will be eliminated.  The bandpass filter can be mode oriented to pitched 
signals (i.e. voice, singing, or instrumental music) or can be modified by 
adding noise to the filter so that un-pitched signals can be effectively 
processed. 

Note:  To aid the user in locating the maximum effective center frequency, a 
       light blue vertical bar is placed at half the sampling rate for the 
       data. 

 The transformation for the Bandpass filter was taken from a a program called 
MUSIC56K (as documented in the MUSIC56K source code) and implemented in C++ for 
this program. 

Operation of the bandpass filter tool is probably one of the most complex 
interfaces in the toolbox.  It is based on a simple principle.  The entire 
display of the filter represents the frequency response of the filter and is 
operated like a slider.  However, since the Start frequency and the Stop 
frequency are independent, the sliding bar is divided into identical controls 
for each filter edge. Before getting into the operation of the controls the 
display needs to be explained to establish the terms that will be used. 

As mentioned, the display is designed to illustrate the frequency response of 
the bandpass filter (independent of any added noise).  The center of the Start 
(Wp) and End (Ws) of the filter are marked by vertical BLUE bars.  The Center 
(Wc) of the filter is marked by a vertical RED bar.  These three markers 
provide the means for the user to modify the filter.  The region to the left of 
the RED center frequency is always the start of the filter.  The user may click 
the mouse to the left of Wp to decrease Wp by 1000 Hz.  Clicking between Wp and 
Wc increases Wp by 1000 Hz.  Likewise, clicking between Wc and Ws decreases Ws 
by 1000 Hz and clicking to the right of Ws increases Ws by 1000 Hz.  The user 
may also click the mouse near Ws or Wp to drag the respective ends of the 
filter quickly. 

To provide fine control of the filter, Right and Left arrows are provided for 
both Wp and Ws.  Clicking on either the right or left arrow will increase the 
indicated filter edge by 1 Hz.  To increase or decrease the filter edges by 10 
Hz, the user may select the plus or minus corresponding to the filter edges. 
The left set of controls affects Wp and the right set of controls affects Ws. 

As the mouse is used to adjust Wp and Ws, the exact frequencies for Wp, Ws, Wc, 
and the filter Width are updated in the text input fields.  The user can use 
the mouse to select one of the input fields and modify it directly.  To accept 
a value in the entry field and recalculated the dependent frequencies select 
another window or click on another item which moves the focus from the 
notebook.  The rules for the fields are as follows: 

 1. If the Center frequency is modified, new values for Wp and Ws are 
    immediately calculated using the current Width. If Wp or Ws are outside of 
    the possible ranges, then Wp or Ws are set to the limit of the acceptable 
    range and the Width and Center are recalculated. 
 2. If the Width of the filter is modified, new values for Wp and Ws are 
    immediately calculated using the current Center frequency.  If Wp or Ws are 
    then outside of the acceptable ranges, Wp or Ws is then set to its limit 
    and the Center and Width are recalculated. 
 3. If Wp is changed, the Width and Center are automatically recalculated to 
    reflect the new start of the filter. 
 4. If Ws is changed, the Width and Center are automatically recalculated to 
    reflect the new end of the filter. 

The bandpass filter has been selected because of the desirable effect on 
typical sounds that will be processed by PMsndX such as voice or music. 
However, if other types of noise are to be filtered, noise can be added to the 
filter which results in a sharper peak of the filter.  To add this noise, 
select the checkbox for "Add filter noise". Selecting the checkbox again will 
disable the filter noise. 

Note:  The display of the frequency response for the filter does not reflect 
       added noise. 


═══ 6.6.6. Low Pass ═══

A Low Pass filter can be applied to a sample to eliminate high frequencies. 
Filtering is accomplished in the digital domain through the use of a very 
simple second order digital Fourier transform.  Future implementation may have 
a more complex Fourier transform; however, the chosen function is desirable 
because it provides a smooth dropoff without significant ringing. The 
performance of the filter is determined by the cutoff frequency and the rate of 
drop.  If the dropoff is made too quickly, the filter will exhibit a ringing 
effect at the begin and end of the dropoff.  If the dropoff is performed too 
slowly, the filter will suppress more frequencies toward the end of the desired 
range.  The more orders of the filter (more stages), the better the frequency 
response; however, more orders increase the time for filtering significantly. A 
two order filter works adequately. 

When performing the digital convolution of the sample with the step function a 
Gain factor is used to normalize the output data.  This acts as a Volume 
control for the sample to prevent losses due to numerical overflow.  Values for 
the gain range from 0 to 1 in increments of 0.01.  A slider bar is used to set 
the gain of the low pass filter.  When the low pass filter is first brought up, 
the Gain will default to a value of 0.8.  If this is changed, it will remain at 
the new setting until the session is terminated. 

The Frequency response of the low pass filter is determined by a the 
centerpoint of the dropoff at the end of the step function.  When performing a 
digital filter, it is not possible to prevent the gradual drop at the end of 
the step function due to the convolution of the samples used in the 
transformation.  This is true for analog components also. The centerpoint of 
the dropoff can be set in three ways. The user may enter the specific frequency 
in the text entry box in the lower right corner or may use the filter display 
like a sliding bar.  As is typical of a sliding bar, the mouse may be used to 
capture the cutoff frequency by pressing the mouse button while the mouse is 
near the cutoff frequency.  By holding the button down, the user may drag the 
frequency to the desired range.  Additionally, the user may click to the right 
or the left of the frequency cutoff to increase or decrease the frequency by 
1000 Hz. The right and left arrows in the corners of the display may be used to 
increase or decrease the frequency by 1 Hz. The plus and minus buttons in the 
corners of the display may be used to increase or decrease the frequency by 10 
Hz. The frequency response curve illustrates the dropoff that occurs at the end 
of the step function. 


═══ 6.6.7. Rate ═══

Once a sample has been loaded into memory, the current rate information is 
displayed on the RATE page of the notebook. The user can change the rate of the 
sample using this page of the tools notebook. 

Note:  Changing the sampling rate may degrade the quality of the sound. 

 The user may select from a set of standard sampling rates for common computer 
formats or may specify a specific rate. OS/2 and Windows use standard rates 
which are multiples of 11025 Hz.  Sun, DEC, and NeXT computers commonly use a 
sampling rate of 8000 Hz.  Standard rates of 8000, 11025, 22050, and 44100 Hz 
have been provided for the user to select. 

If the user wishes to use a sampling rate which is not one of these, the button 
for Non-Standard should be pressed.  This will activate the slider bar and user 
input windows to allow the user to specify the rate.  The slider bar can be 
used to quickly change the rate in the input window or the user may select the 
input window and type in the desired rate. 


═══ 6.6.8. Speed ═══

This function will change the playback speed of a sample. This is the same 
thing as setting a phonograph to a different speed such that the sound is 
played too fast or too slow.  The controls for this effect simply specify the 
new playback speed.  Once a new speed is selected, the sample is resampled to 
interpolate the new playback points. As a result, a sample is still played at 
the same rate, but the data is modified to play at the new rate.  This allows 
the sample to be stored in a file which is of a standard rate. 

The user may select any of the standard rates including 8000 Hz, 11025 Hz, 
22050 Hz, and 44100 Hz.  Additionally, the user may specify the playback speed 
to be either double (x2) or half (x1/2) or may specify a specify playback speed 
by selecting the User button.  If a speed other than the current speed is 
specified, the DOIT button will be activated which will allow the user to 
perform the change. 


═══ 6.6.9. Echo ═══

The echo effect will modify a sample to provide attenuation at specific points 
in a sample.  The operator must specify the points where the echo effects are 
to start and an attenuation or Volume for the echo.  The attenuation determines 
the length of time that it takes for the echo to die away.  If the Attenuation 
specified for all of the echo points is greater than 1, then the echo will 
"melt" rather than fading away and consequently may take a long time to 
complete.  If an attenuation is set to 0 or less, the Echo point is ignored. 

The echo effect presents an interesting challenge to the user interface.  How 
do you provide the user with an intuitive method to set the echo locations and 
the strength of the echo from a dialog box?  Well, look at the ECHO notebook 
page and follow along in the explanation of the operation.  This notebook page 
includes a graphical display of the current sample, a text entry field for 
editing (e.g. adding or deleting) time marks, and a volume control for setting 
the strength of the echo. 

The ECHO notebook is centered around the graph at the top of the page.  This 
display is the primary point of control. However, to allow for a bit more 
direct control, the user may use the entry fields to add and delete echo points 
too. To explain it all, I will start with the graphical display first and then 
lead to the secondary controls. 

Once a sample has been loaded into memory, the graphical display will become 
active.  The display is controlled through two slider bars for the position in 
the sample and for the magnification. The sample is normalized so that the 
largest sample value will hit the limit of the display.  This makes the display 
volume independent but gives maximum clarity of the actual waveform in memory. 
Markers may be added or moved to set the echo points in the waveform.  To aid 
the operator in locating the desired echo point, the display contains a status 
bar for the starting timemark for the sample in the window, the current 
timemark under the mouse, and the magnification factor. 

To move to the right or left in the display, the horizontal slider bar may be 
used.  Pressing the end arrows moves the display one displayed sample to the 
left or right.  When the slider bar is pressed, the display will move one half 
screen to the right or left.  The user may move the display to a region quickly 
by selecting the slider button and dragging it to the appropriate position. 
The display is immediately updated to display the current position. 

The display area at the bottom of the graph provides a timemark indicator for 
the first sample appearing at the left of the graph.  This provides a reference 
for moving through the data.  The time marker is displayed in the form of 
m:ss.ssss where m is the number of minutes into the sample and ss.ssss is the 
number of seconds into the sample. 

Even the smallest sample contains more data than can fit on the graphical 
display.  For this reason the vertical slider to the right of the graphical 
display is used to adjust the viewing magnification of the samples.  The 
maximum magnification of the samples is determined by the length of the sample 
and is calculated by dividing the total sample length by the largest number of 
data points which may be scrolled through on the display.  The display is 
limited to the maximum size of an signed 16 bit value due to the limitations of 
the signals for the horizontal slider bar. This results in a maximum of 32767 
data points which can be displayed and scrolled through. 

Initially, the magnification is set for the maximum displayable.  To decrease 
the magnification ( i.e. zoom out) on the sample, move the slider down the bar. 
The arrows on the ends of the bar can be used to increase or decrease the 
magnification in increments of 1.  Selecting between the button and the arrows 
doubles or halves the magnification. If the button is selected, the 
magnification can be set immediately to a value.  Markers are displayed for the 
nearest point in the zoom.  However, markers can only be set on exact multiples 
of the zoom.  Therefore, when trying to move a marker, if it is set at a 
different magnification, it may not be possible to move the marker without 
returning to that zoom.  Essentially, the marker is displayed but cannot be 
selected because that exact sample point is not visible. I considered making 
the mouse select the nearest marker, but this is a point of confusion if many 
markers are displayed at the same location for a specific magnification. 

The current magnification is displayed in the status area of the display in the 
form of "x1/nnnnn" where "nnnnn" is replaced by the current magnification 
number (i.e. number of points represented by a single point on the display). 
If the display says that the zoom is x1/2, then the magnification of the 
display is halved.  If this sounds confusing, then just play with the notebook 
page for a bit to get a feel for the operation of the zoom. 

Before going on, another area of the display needs to be described.  The center 
number on the status area of the display indicates the timemark for the current 
(or last) mouse position. Whenever the mouse is moved into the display area, 
this number will be updated to indicate the time offset for that particular 
point.  This takes into account the magnification. 

Now for the fun part.  To add an echo point to the sample, move the mouse to 
the place where you desire the echo.  The status display will provide a 
reference for the timemark. When the proper position has been selected, click 
the mouse and a blue marker will be placed.  If the mouse is released, the 
marker will be set at that location in the sample.  If the mouse is not 
released, the marker may be dragged across the display. This marker may be 
moved later if necessary by other means too. 

Note:  If at any time the mouse pointer is moved outside of the display before 
       the mouse button is released, the marker will not be set and the blue 
       mark will be erased from the display. 

 A echo marker may be moved by positioning the mouse pointer over the marker 
and pressing the mouse button.  If the marker is on a multiple of the zoom 
level, it will be selected and will follow the mouse as long as the button is 
pressed.  When the button is released, the marker will be placed at that 
position. 

A marker may be moved to another time delay by entering the desired delay 
directly through the Time Mark entry field. 

Note:  If the mouse is moved off the display area, the marker will be restored 
       to its original position. 

 For each marker displayed, the timemark is stored in a Combo Box.  This box is 
like an entry field in that the user can edit the time directly; however, it 
also has a drop down box that can scroll vertically through all of the 
different markers.  This type of box provides a great deal of flexibility for 
the user. 

To add a marker at a specific time, position the cursor in the Timemark box and 
edit the time index.  The format is the same as that used to display the time 
marks in the main display.  Enter the number of minutes followed by the 
seconds.  The granularity of the seconds is on the order of 1/10000 of a 
second.  For example, entering 6:54.4253 would accept a time mark at 6 minutes, 
54.4253 seconds.  If a value is entered with is beyond the maximum sample of 
the file or less than 0, then the data is ignored. 

Once the desired time mark has been entered, the user may press the Add button 
to place the marker in the current database.  All timemarks added to the 
display use the volume specified for the last timemark, or 0 if no volume has 
been set yet. 

When the listbox is pulled down for the timemarks, each of the timemarks that 
have been entered are displayed in a vertically and horizontally scrollable 
window.  Up to 32 markers may be placed in the file and any markers which are 
unused are displayed with the word "EMPTY".  The markers are placed in the 
database in the order that they are entered unless a free slot is open (from 
being deleted).  The user may select any of the time marks using the combo box. 
If the selected timemark is not empty, the display will be updated to display 
the selected timemark in the center of the graph.  In the event that the 
timemark is too close to the end or beginning of the sample to display in the 
center of the graph, the timemark will be displayed without being centered. 
Once a timemark has been selected, the Del button may be pressed to delete the 
marker from the database.  The entry field is not cleared in order to allow the 
user to directly edit the timemark which was deleted and add it later. 

The volume for each timemark may be set by specifying a value in the volume 
entry field.  This is a simple entry field in which the user can type or delete 
numbers.  Since the volume (attenuation) for each timemark may range from 0 to 
infinity, the only method for entering the volume is through the keyboard. 
Sorry, no sliders here.  As each character is typed, it is stored.  The user 
does not have to press enter or any key to accept the value. 

I have not found a big use for numbers greater than 1, but I could not find any 
reason to limit the user to a specific range of numbers.  Anyone who has 
experience with this effect and knows of a reason for a limitation should 
contact the author and I will be happy to set up something to make entry of the 
Volume easier. 

Note:  The most common mistake for the echo effect is in forgetting to enter a 
       value in the Volume field.  Remember that you must provide an 
       attenuation for the echo in the Volume entry field to make the echo 
       point valid. 


═══ 6.6.10. Invert ═══

A sample is composed of numbers which are digital snapshots of an analog wave 
at regular intervals.  These numbers can take on positive and negative values 
which push or release the cone of a speaker to produce sound. The range and 
channels for this function are selected through the editor. 

Any series of samples may be inverted such that all positive values become 
negative and all negative values become positive.  To the human ear, there is 
no difference in the sound produced; however, mathematically, the new wave is 
very different.  An inverted wave may be added to a normal wave to 
mathematically subtract one from another. When this function is combined with 
the MERGE function of the editor, samples can be added together to eliminate 
common frequencies. 


═══ 6.6.11. Reverse ═══

This effect allows the user to reverse a section (or all) of a sample.  The 
range and channels for this function are selected through the editor. 


═══ 6.6.12. Vibro ═══

This function performs the "world-famous" Fender Vibro-Champ sound effect to a 
sound sample by using a sine wave as the amplitude of the volume at each 
sample.  This tool requires that the user set the Speed and the Depth of the 
sine wave. 

The speed setting gives the frequency of the sine wave in Hertz.  The range of 
values for the slider are from 1 to 30 in increments of 1 Hertz.  A value of 0 
would be useless for a frequency and is not allowed. 

The depth setting gives the amount by which the volume will be cut into by the 
sine wave.  The range of values for the slider are from 0.0 to 1.0 in 
increments of 0.01.  The initial value of the slider is 0.5. 


═══ 6.6.13. Volume ═══

Most anyone who has received a sound sample from different sources has had the 
problem that the recorded volume is inconsistent between different samples. 
After all, there is no standard recording level for the different machines or 
different software. 

To allow the user to adjust the volume of a sample, PMsndX provides a tool 
which can either adjust the volume by multiplying every sample by a fixed 
amount or by multiplying the samples by a value based on the limit of the data 
that can held in memory. 

By specifying a maximum value for the sound sample, all sound samples can be 
set to have a similar maximum.  The obvious use for this function is to allow a 
library of sounds to be set at the same volume.  The value used for the maximum 
volume is based on a percentage of the maximum data that can be held in a 
single sample.  As an example, a value of 100% for the volume represents a 
value of 127 for a signed byte sample. 

When the button for the Maximum is selected, the slider bar directly beneath 
the button is activated.  Initially, this will be set to the current volume in 
terms of the percentage of the maximum value for the sample.  The volume may be 
adjusted by setting the slider to a value between 0 and 100 percent of the 
maximum. 

Since the value is based on a percentage of the maximum value of the data that 
can be stored in a sample, clipping is not possible. 

When the button for the Fixed value is selected, the slider bar directly 
beneath the button is activated as well as the checkbox for clipping.  The 
fixed bar provides the means to multiply all sound samples by a fixed value 
between 0 and 2 in increments of 0.1. A value of 1 makes no change.  Any value 
greater than 1 increases the volume and any value less than 1 decreases the 
volume.  A value of 2 doubles the volume of the sample. 

When using fixed sampling it is possible to exceed the maximum data that may be 
stored for a sample.  The Allow Clipping checkbox may be selected to allow the 
data to be clipped.  If the checkbox is not set and if the fixed multiple will 
result in clipping, then the multiple will be set to the maximum value that 
will not result in clipping.  If the clipping box is set, data may exceed the 
maximum that may be stored for the sample which will result in noise. 


═══ 6.6.14. Fade ═══

This effect allows the user to either fade in or fade out the volume of a 
sample.  Fading the data in a sample is produced by increasing or decreasing 
the volume of the sample over a period.  To fade a sample in is to slowly 
increase the volume of the sample from 0 to the normal volume of the sample 
over a block of time.  To fade the sound out is just the opposite in which the 
volume of the sample is slowly reduced over a period. 

The FADE tool provides three methods for fading which provide a robust means 
for controlling the volume of the data over the specified range of operation. 
These are Linear, Slow Geometric, and Fast Geometric. 


═══ 6.6.15. Balance ═══

When a sample has more than one channel, the volume of the individual channels 
can be varied.  The balance of the channels can be achieved either 
instantaneously or over a period of time.  These are the same basic functions 
as used in the FADE and SWAP effects and are Linear, Slow Geometric, and Fast 
Geometric, and Step. 

The volume of a sample may vary by either starting at the specified percentage 
of the current volume for each channel and progressively approaching full 
volume.  This is similar to fading in a sample and is achieved by selecting the 
"IN" button.  The opposite effect is achieved when the volume starts at the 
current volume and progressively decreases to a percentage of the current 
volume. 

When balancing a sample, the user must specify a percentage for each channel. 
When fading in, this is the percentage that the volume will start at for each 
respective channel. When fading out, this is the final percentage of the 
original volume.  The display at the top of this dialog varies depending on the 
number of channels in the current sample. 


═══ 6.7. Help ═══

PMsndX is equipped with extensive on line help that can be accessed by pressing 
the HELP button from the main control panel.  When this button is selected a 
window will appear which will display the table of contents for the system. 

Links to other text is displayed in a blue-green color and can be selected to 
jump to that description in the text. When the control panel buttons appear in 
a tabular form, the buttons are active links in the help like the blue-green 
colored text.  Pressing these buttons will jump to the respective text. 


═══ 6.8. Exit ═══

When the EXIT button is pressed, the program terminates.  If the Settings box 
or the SAVE DIRECTORY from the Open or Save dialog boxes have been set to save 
information, the data will be saved to the initialization file before the 
program exits.  Before exiting, PMsndX requests verification that the user 
wants to exit to prevent accidentally exiting. All windows of PMsndX including 
any dialog boxes are removed from the screen when the program terminates. 

If the data in the memory buffers has been modified, PMsndX will warn the user 
that there are modified buffers and ask for verification that the user really 
wants to exit. 


═══ 7. Technical Issues ═══

Memory Usage: I have worked with means for storing and converting from one 
format to another efficiently.  Initially I tried to store things in a data 
structure which was a union of all of the types of data that are used by the 
computers.  However, converting from one format to another was difficult and 
each effect had to be able to understand the initial and final format.  This 
became unwieldy considering that there can be either signed or unsigned samples 
of sizes byte or word.  As new effects were added, it became unmanageable.  At 
a sacrifice to memory efficiency, I have changed it to store all data as a 
signed SHORT (2 byte) sample.  The effects then operate generically on the 
samples and the only time that the type of data is important is when reading or 
writing the samples.  The savings in complexity justified the memory 
requirements.  As a result, if a sample is 1k of bytes (.wav format), then in 
memory it will take up 2k.  Currently the program will only read and write 8 
and 16 bit samples. Since I don't know of any sound cards that can sample at 
greater bit sizes, this is the limit.  In the future, this approach to memory 
usage can be easily extended to 32 bits without rewriting every part of the 
program.  In fact, to change the storage sizes, two definitions have to be 
changed and then the proper input/output routines written.  Simple? I think so. 

Additional known faults: 

 1. The button for Record has no function at this time.  This functionality 
    will be added later. 
 2. There is no drag and drop capability yet. 


═══ 8. About the Author ═══

My name is William Scott Hiles but I usually go by the name Scott.  I have a 
masters degree in signal processing and satellite communications. 
Unfortunately, my occupation utilizes very little of my formal education and 
takes more advantage of my less formally learned talents.  I work as an 
electrical engineer for the Navy in the area of LAN and WAN research. My job is 
centered around promoting open systems in networking within the Navy and I am a 
Navy expert on fiber optic networking.  I have worked with the ANSI X3 
committees for the past 5 years and currently (1993-1994) am the chairman of 
the FDDI Repeater specification.  Enough of that dribble...the point is that I 
don't use my education in my job. 

Which leads me into the purpose of this program.  I am an electrical engineer, 
and my heart lies in hardware design and programming.  Well, with this program 
I can at least satisfy my need to create software.  So, this program came about 
because I was playing with sampling and recreating sound with my Sound Blaster 
16 when I had the need to convert from the .wav format to the Sun .au format. 
After finding a little program that would convert Sun audio files to the PC 
format I found that it had problems with the new version of .WAV files.  So, I 
set out to write something that worked with the latest versions.  Well, from 
there it was not difficult to add other formats, and then I started playing 
with manipulations and so forth.  Over about 9 months of very time consuming 
work, I came up with the present program called PMsndX. 

My resources are modest.  I am 29 (1993) and have programmed everything from a 
PC to a 486 for the past 10 years.  I dumped my 286 in February of 1993 and got 
me a nice 486.  I decked the thing out and got OS/2.  I had been playing with 
OS/2 since 1.3 on machines that I did not own, but this was the first time I 
had it at home to play with as I pleased. Programming under OS/2 provided a 
unique challenge with unlimited creative abilities.  The company called 
WiSHware which is listed in the About box was formed as a shareware/freeware 
incorporated name for anything I write.  I have a significant library of 
programs for DOS and even a couple for Windows.  PMsndX is the second program 
for OS/2 that I have written.  The first one was not well received as it did 
not provide a significant function to the community.  Big deal.  I use it at 
home and I don't care. 

So that is my history and my qualification.  I am a bit surprised that you read 
this far.  Congratulations. By the way, did you wonder why I chose a little 
blue motorcycle for the icon? Very simply put, the modern day sportsbike 
represents the art of functional integration while still maintaining the 
quality and sound of much more expensive motorcycles. 

I can easily be reached by my current email address 
(whiles@relay.nswc.navy.mil) or through US mail at: 

Scott Hiles 
4421 Savannah St. 
King George, VA 22485 


═══ 9. Shareware ═══

During the development stages of PMsndX (i.e. until version 1.0 is available) 
PMsndX is free to all for distribution. After version 1.0 is finished, the 
program will then be distributed as shareware.  Anyone who does not want to 
register later versions will still be able to use all of the releases before 
1.0. 

Licensing and registration fees apply to the user interface and style of the 
program but do not apply to the algorithms used to create the effects.  These 
algorithms are public domain and may be copied and distributed freely. 

I have put a lot of effort into making this program robust and very pleasing. 
It has taken me more than nine months and 24,000 lines of code to get this 
program to where it is now, and I would hope that if you like the program and 
use it, you will appreciate it enough to send me a little cash to help fund 
future work.  I don't expect much. 

Asking for money is a sticky thing.  The big problem is to give people a 
program so that they can play with to see what it can do and yet hold back 
enough to get people to want to register the program.  I put a lot of thought 
into this and have considered the many ways that authors achieve their goals. 
My solution was to disable the ability to read or write any formats other than 
the PC .WAV and the Sun .AU types, and disable the UNDO capibility. 
Additionally, the multi-channel capability of the program is disabled and the 
clipboard will not copy or cut anything less than the entire sample in memory. 


═══ 10. Registration ═══

I have three options which I can offer which seem to follow with common 
SHAREWARE practice.  I have looked in stores for something that provides 
anything similar and found that a commercial product for Windows with half the 
functions cost considerably more.  A registration form is provided and the 
following are the options for registration. 

1.  $15.00 will get you a password that will enable all of the functions of the 
current version. 

2.  $30.00 will get you a password that will enable all of the functions for 
all versions up to the next major release.  If you chose to register using 
option 1 first and then want to upgrade, I will give you a $10 credit and you 
can get option 2 for $20.00. 

3.  $50.00 will get you a password that will enable all of the functions for 
all future versions.  If you have chosen to register using option 2 first, I 
will give you a $20 credit and you can get the lifetime registration for 
$30.00.  If you have registered with option 1 first, then I will give you $10 
credit and you can get the lifetime registration for $40.00. 

Note:  Please note.  These prices cover just the registration.  Shipping 
       charges for the disks through the Postal service are extra.  If you 
       order the program through the mail, add $3.00 to cover the media and 
       shipping costs. 

 The section describing the Author provides my email and US postal mail 
addresses. 

Now, what do you get when you register.  Well, you obviously get a password 
that will enable all functions of the program.  The functions that are disabled 
for unregistered users are: 

Formats   Only .AU and .WAV formats can be loaded and saved 
Editor    The Cut and Paste operations of the editor only work for the full 
          sample (i.e. will not work for ranges) 
Undo      The UNDO function is disabled 

In addition to that, I can provide limited technical support through regular 
phone service, email, or the US Postal service.  A number of people have 
contacted me to ask for special programs (e.g. programs that will just play any 
format without the overhead of the editor or a program that will just convert 
between formats).  These will be fairly easy to create using the existing 
objects of PMsndX.  If you are registered for PMsndX, these programs will 
automatically recognize the registration and work on your system. 

If and when you register, you will receive a password through whatever means 
that you prefer.  If you choose the postal service, you will receive it via 
disk along with the latest copy of the program (remember to include an 
additional $3.00 to cover the shipping and media).  If you choose to receive 
your registration through email, you will receive an email message that can be 
imported using the FILE button of the registration dialog.  Registrations will 
be sent after your form of payment has cleared. 

Although not currently provided, credit cards will eventually be accepted if 
the program makes enough profit to afford the service.  Please allow at least 
two weeks to receive your registration. 

Since PMsndX is provided as ShareWare, there is no provision for refunds.  In 
the event that you are dissatisified with the operation of PMsndX due to an 
error in loading or saving a format, contact me and I will fix the program if 
you can provide me with a copy of the file that is causing the problem. 


═══ 11. Entering Registration Info ═══

Once you receive your registration you have a couple of options for entering it 
into the program.  First, pull up either the Welcome or About dialog box from 
the system menu of PMsndX.  Press the REGISTER button to bring up the 
registration dialog box. 

You may enter the data directly into the entry fields or you may have the 
program scan a data file for your registration information. When entering data, 
enter it exactly as it is shown in the file or text for your registration.  The 
Name field must not have any additional spaces and it must be entered in exact 
case. The password is 16 characters long and will never contain any space 
characters.  It is case sensitive so be careful to get the case right. 
Passwords never contain the upper case letter O or the upper case letter I to 
avoid confusion with similar looking numbers. 

When PMsndX scans a file for the password information, it looks for the 
following keys: 

PMsndX Name: 
Through version: 
PMsndX Password: 

These lines can be anywhere in a file so there is no need to remove a mail 
header or extra information.  PMsndX will search the file for the specific text 
that it is looking for and extract it. 

The registration information is stored in the file called os2.ini.  This allows 
a copy of PMsndX to be run from a network and each machine can have it's own 
registration. This also allows the pmsndx.ini file to be copied form one 
machine to another without violating the licensing agreement.  Four items are 
stored in the os2.ini and total about 100 bytes.  Any .ini editor can be used 
to remove this information if the user wishes to delete PMsndX from the system. 

Note:  The information in the os2.ini file is only written when the program is 
       registered.  This avoids adding stuff to the os2.ini file unless the 
       user has chosen that the program is worth keeping. 


═══ 12. Tradeoffs ═══

When PMsndX is operating on a sample for the clipboard, playback, or the tools, 
it stores the entire sample in memory.  This has the advantage that the program 
can double buffer the sample for faster operation; but, it has the disadvantage 
that it can take up a tremendous amount of memory to hold large samples. 
PMsndX provides the user with a simple interface at the expense of resources on 
the host computer. 


═══ 13. Copyright ═══

The author makes NO WARRANTY or representation, either expressed or implied, 
with respect to PMsndX, its quality, accuracy, merchantability, or fitness for 
a particular purpose.  This software is provided "AS IS" and you, its user, 
assume the entire risk as to its quality and accuracy. 

This software is copyright (C) 1994, William S. Hiles.  All rights Reserved 
except as specified below. 

Permission is hereby granted to use, copy, and distribute this software (or 
portions thereof) for any purpose, without fee, subject to these conditions: 

(1) The seven files, pmsndx.exe, pmsndx.hlp, readme.txt, history.txt, 
license.txt, order.txt and file_id.diz must always be included during 
distribution. Any alterations to the files must be clearly documented.  No 
changes may be made to the About screen or any of the copyright information. 

(2) Permission for use of this software is granted only if the user accepts 
full responsibility for any undesirable consequences.  The author accepts NO 
LIABILITY for damages of any kind. 

(3) Permission is not granted for the use of the author's name or company name 
in advertising or publicity relating to this software or products derived from 
it. 

(4) Users are granted permission to collect fees for the distribution of 
PMsndX, (such as BBS's that have a membership fee or a downloading charge, or 
FTP sites that sell cdrom versions of their archives) but users are 
specifically prohibited from selling PMsndX as a product or bundling PMsndX 
with other products that are then sold. 

(5) Unless otherwise negotiated in writing with the Author, registration 
passwords for PMsndX may not be distributed in part or in whole.  Registrations 
are provided to individuals (or for site licensing as negotiated at time of 
registration) and may not be distributed or transferred. 


═══ 14. Acknowledgements ═══

Of course, IBM deserves a great deal of recognition for providing an operating 
system that is robust and stable and affordable enough for the general user. 
Many thanks to IBM for a fine job on creating OS/2. 

A special thanks is required for Linden deCarmo for his help in understanding 
the MMPM/2 portion of OS/2. 

Many thanks to the fine group of people who made suggestions for corrections 
and improvements in this program.  This team of very patient individuals from 
around the world comprised the Beta Test team.  Each and every one of them 
contributed in some way to the development of PMsndX.  Their names are listed 
below (in alphabetical order). 

David Charlap 
Christopher W. Curtis 
Linden deCarmo 
Terrance L. Eck 
Scott E. Garfinkle 
Jesse Gearhart 
Nicole Greiber 
Christopher Hemmer 
Rick Huebner 
Mark R. Johnson 
Dov Nelkin 
Lara Olofsson 
Steve Patrick 
Rupa Schomaker 
Kamal Shakker 
Brett Sherron-Ferrell 
Jimmy Shaw 
Kent Williams 

And of course, that special person and the kids who took the many hours of 
clicking away at the keyboard in stride.  They stuck by me throughout this 
entire thing, read all the documentation, tested the user interface, and 
actually began to understand how sound really works. 

Sounds like a Grammy award, huh. 


═══ <hidden>  ═══

JoeView is an excellent program written by Joe Burkley.  If you ever need to 
view a graphics image of virtually any format, this is the program for you!!! 


═══ <hidden>  ═══

The only exception to the operation of the control panel buttons is the HELP 
button.  Since the HELP is spread across all dialogs within the program, the 
help system is independent of the source of its invocation.  For this reason 
the HELP button is not animated. 


═══ <hidden>  ═══

The .WAV format is actually defined as a RIFF file.  The header and data are 
very robust and there are extensions for proprietary keywords and formats. 
PMsndX only supports the standard PCM format and will not load proprietary 
formats.  You will receive a STYLE error if it contains an unsupported format. 


═══ <hidden>  ═══

The bits in a word are stored such that the leftmost bit is stored first in the 
first byte and the rightmost bit is stored last in the last byte.  If a word is 
composed of 16 bits, the word would be written to a file starting with bit 16 
and ending in bit 0. 

The number 0x1234 (0001 0010 0011 0100) is actually stored as 0001 0010 0011 
0100. 


═══ <hidden>  ═══

The bits in a word are stored such that the leftmost bit is stored first in the 
last byte and the rightmost bit is stored last in the first byte.  If a word is 
composed of 16 bits, the word would be written to a file starting with bit 7 
and ending in bit 8. 

The number 0x1234 (0001 0010 0011 0100) is actually stored as 0011 0100 0001 
0010. 


═══ <hidden>  ═══

There are four methods of transitioning channels in a sample. These methods are 
used in various tools to provide a smooth transition from one end of a range to 
another.  The four types of transitions are listed in the following text. 

The first method is linear.  In this case, the increase or decrease in the 
volume is constant over time.  This can be defined by the mathematical 
equation: 

volume(t) = volume(t) * t/interval 

A second method for adjusting the volume is to use a geometric expression so 
that the sample transitions slowly in the beginning of the range and then 
changes quickly toward the end of the range. To transition a sample out slowly 
over time a form of the function: 

volume(t) = volume(t) * (1 - (t/interval))¤ 

The third method is exactly the reverse of the slow transition in which the 
transition moves very quickly in the beginning of the range and then slowly 
reaches the end of the range. The equation for this is as follows: 

volume(t) = volume(t) * (t/interval)¤ 

Finally a fourth method is to have the samples make an immediate transition or 
a step.  In this case, the transition is made immediately at the beginning of 
the range.